Node / rns-mirrors / Reticulum-Go.git / files / docs / en / getting-started.md

Displaying Rendered • View raw • Download

• Go 1.26.5 or later

• Make or Task (optional, for convenience targets)

• A writable home directory for T383838~/.reticulum-go

The repository vendors dependencies. A normal build does not contact module proxies when T383838GOFLAGS=-mod=vendor is set (default in the Makefile and Taskfile).

From the repository root:

T282828

This produces T383838bin/reticulum-go as a static stripped binary (T383838CGO_ENABLED=0) with the daemon and all tools as subcommands.

Equivalent manual command:

T282828

T282828

Default prefix is T383838/usr/local. That installs T383838reticulum-go, legacy tool symlinks (rgostatus, rgoid, …), and man pages (reticulum-go(1), reticulum-go(8), and tool pages). Override with T383838make install PREFIX=/opt/reticulum. Staging: T383838make install DESTDIR=/tmp/stage PREFIX=/usr.

Or install into your Go binary directory:

T282828

Linux packages:

T282828

Arch Linux and CachyOS: add the Quad4 pacman repo from quad4-arch (T383838reticulum-go or T383838reticulum-go-git). That is a Quad4-hosted repo, not AUR.

T282828

Or:

T282828

On first start the daemon creates T383838~/.reticulum-go/ with a default config if none exists. Logs go to stderr by default. Set verbosity with T383838[logging] loglevel (1 through 7). Set T383838[logging] destination = file|both and optional logfile to write to disk (default T383838{config_dir}/logfile/reticulum.log). Daemon text logs, pageserver banner, and CLI tools color on TTY. Respect T383838NO_COLOR and T383838FORCE_COLOR / T383838CLICOLOR_FORCE.

Daemon flags:

T282828

Pass T383838--config / T383838-config with a config file or directory (directory uses config inside it).

A useful starting point enables transport and one UDP interface to a known peer:

T282828

UDP requires an explicit targetaddress or targethost. Open binds do not learn peers from the first inbound packet (same policy as Python forward_ip).

For local mesh discovery over IPv6 link-local multicast, use AutoInterface. See Interfaces.

T282828

Full test suite:

T282828

Cross-reference tests against Python vectors (requires Python 3 and vector generation):

T282828

T282828

Legacy Windows 7, 8, and 8.1 builds use go-legacy-win7:

T282828

Install Task and run:

T282828

See Embedding and WebAssembly.

Build the shared library and optional binding tests:

T282828

T383838task test-odin needs the Odin compiler on T383838PATH. T383838task test-zig needs Zig 0.16.0 or later on T383838PATH. T383838task test-cpp needs CMake and a C++17 compiler. See librns.

T282828

Needs the Dart SDK on T383838PATH. FFI uses librns on Linux, Android, and Windows. See librns and Control API.

Add to T383838[reticulum]:

T282828

Generate a random 32-byte key and encode as hex. Clients send T383838Authorization: Bearer <rpc_key>. See Control API.

Tools are subcommands of the single T383838reticulum-go binary (T383838make build). Legacy names (rgostatus, …) install as symlinks via T383838make install.

To query a running Python rnsd from T383838reticulum-go status / path, point T383838-config at T383838~/.reticulum. On Linux both stacks default to abstract Unix sockets when sharedinstancetype is unset, so no TCP rewrite is required:

T282828

Prefer an explicit shared rpc_key when mixing stacks. Use T383838shared_instance_type = tcp only when you want the same recipe on every OS.

Full flag reference, T383838.rsg / T383838.rsm / T383838.rfe usage, file transfer, and troubleshooting are in CLI utilities.

Sandboxing is on by default. To turn it off (not recommended for production):

T282828

See Security for platform behavior.

Daemon exits on config error. Check the config path and syntax. Unknown keys are ignored so a damaged file can still boot. Fix typos in type and interface names.

No paths to remote destinations. Confirm interfaces are enabled, peers are reachable, and transport is enabled. Use debug level 5 or higher temporarily. Request paths explicitly from application code or the control API.

IFAC mismatches. Peers must use the same network_name and passphrase. Wrong IFAC frames are dropped silently on ingress.

Shared instance conflicts. Only one process should own interfaces when T383838share_instance = yes. Others should connect as clients. Check sharedinstanceport (default 37428).

status connection refused. Point T383838-config at the daemon config dir (T383838~/.reticulum for rnsd). Align sharedinstancetype and instance_name / ports, or leave the type unset on Linux for Unix. See CLI utilities.

Permission errors on Linux sandbox. Landlock requires kernel 5.13+. The config directory and storage paths must live under whitelisted locations. See Security.